home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Orlando_1993 / Devcon93.4 / CAMD / docs / camd.autodoc < prev    next >
Encoding:
Text File  |  1993-01-11  |  34.1 KB  |  1,104 lines
  1. TABLE OF CONTENTS
  2.  
  3. camd.library/AddMidiLink
  4. camd.library/CloseMidiDevice
  5. camd.library/CreateMidi
  6. camd.library/DeleteMidi
  7. camd.library/EndClusterNotify
  8. camd.library/FindCluster
  9. camd.library/FindMidi
  10. camd.library/FlushMidi
  11. camd.library/GetMidi
  12. camd.library/GetMidiAttrsA
  13. camd.library/GetMidiErr
  14. camd.library/GetMidiLinkAttrsA
  15. camd.library/GetSysEx
  16. camd.library/LockCAMD
  17. camd.library/MidiLinkConnected
  18. camd.library/MidiMsgLen
  19. camd.library/MidiMsgType
  20. camd.library/NextCluster
  21. camd.library/NextClusterLink
  22. camd.library/NextMidi
  23. camd.library/NextMidiLink
  24. camd.library/OpenMidiDevice
  25. camd.library/ParseMidi
  26. camd.library/PutMidi
  27. camd.library/PutMidiMsg
  28. camd.library/PutSysEx
  29. camd.library/QuerySysEx
  30. camd.library/RemoveMidiLink
  31. camd.library/RethinkCAMD
  32. camd.library/SetMidiAttrs
  33. camd.library/SetMidiLinkAttrs
  34. camd.library/SkipSysEx
  35. camd.library/StartClusterNotify
  36. camd.library/UnlockCAMD
  37. camd.library/WaitMidi
  38. camd.library/AddMidiLink                               camd.library/AddMidiLink
  39.  
  40.    NAME
  41.        AddMidiLink -- Create a MidiLink to a MidiCluster.
  42.  
  43.    SYNOPSIS
  44.        struct MidiLink *AddMidiLinkA (struct MidiNode *mi, LONG type,
  45.                                                a0                d0
  46.                 struct TagItem *TagsList)
  47.                         a1
  48.  
  49.         struct MidiLink *AddMidiLink(struct MidiNode *mi, LONG type,
  50.                         Tag type1, ...)
  51.  
  52.    FUNCTION
  53.        Creates a MidiLink structure and connects it to a MidiCluster.
  54.  
  55.        The first form of the function expects a tag array pointer or NULL.
  56.        The second form permits the tag items to exist on the caller's
  57.        stack.  In both cases, the final tag item must be TAG_END.
  58.  
  59.    INPUTS
  60.         mi - MidiNode that the MidiLink should communicate through.
  61.  
  62.         type - Type of link, either MLTYPE_Receiver or MLTYPE_Sender.
  63.  
  64.        TagList   - optional pointer to tag array.  May be NULL.  For
  65.                    OS v1.3, there are restrictions on the tag array
  66.                    contents.  See NOTE below.
  67.  
  68.    TAGS
  69.         See SetMidiLinkAttrsA
  70.  
  71.    RESULTS
  72.        A pointer to a MidiLink structure on success or NULL on failure.
  73.        When FALSE is returned, an error code will be returned if a TagItem
  74.         with an ti_Tag of MLINK_ErrorCode was provided. The CME_ error code
  75.         will be put in the ti_Data field.
  76.  
  77.    NOTE
  78.        Under 1.3 only a restricted tag array may be passed into this
  79.        function. Specifically, the only special tag values that are
  80.        supported are TAG_END (or TAG_DONE) and TAG_IGNORE.  All others
  81.        (e.g. TAG_SKIP, TAG_MORE) are treated as TAG_END.  The full range of
  82.        TAG list operations are permitted under 2.0.
  83.  
  84.        This function MUST be called by a Process (not a Task).  It makes a
  85.        few DOS calls.
  86.  
  87.    EXAMPLES
  88.        ml = AddMidiLink (mi,MLTYPE_Receiver,
  89.                MLINK_Name, "app.in", MLINK_Location,"in.0", TAG_END);
  90.  
  91.        Creates a receive MidiLink named "app.in" to the MidiCluster named
  92.         "in.0", where all bytes are recevied through the MidiNide mi.
  93.  
  94.    SEE ALSO
  95.        RemoveMidiLinkA(), SetMidiLinkAttrs()
  96.        2.0 tag docs.
  97. camd.library/CloseMidiDevice                       camd.library/CloseMidiDevice
  98.  
  99.    NAME
  100.        CloseMidiDevice -- Close a MIDI device driver.
  101.  
  102.    SYNOPSIS
  103.        void CloseMidiDevice (struct MidiDeviceData *MidiDeviceData)
  104.                                          a0
  105.  
  106.    FUNCTION
  107.        Closes a MIDI device driver opened by OpenMidiDevice().
  108.  
  109.    INPUTS
  110.        MidiDeviceData - pointer to a MidiDeviceData structure returned by
  111.                     OpenMidiDevice().
  112.  
  113.    RESULTS
  114.        None
  115.  
  116.    SEE ALSO
  117.        OpenMidiDevice()
  118. camd.library/CreateMidi                                 camd.library/CreateMidi
  119.  
  120.    NAME
  121.        CreateMidi -- Create a MidiNode.
  122.  
  123.    SYNOPSIS
  124.        struct MidiNode *CreateMidiA (struct TagItem *TagsList)
  125.                                                a0
  126.  
  127.        struct MidiNode *CreateMidi (Tag tag1, ...)
  128.  
  129.    FUNCTION
  130.        Creates a MidiNode structure with the desired attributes.
  131.  
  132.        The first form of the function expects a tag array pointer or NULL.
  133.        The second form permits the tag items to exist on the caller's
  134.        stack.  In both cases, the final tag item must be TAG_END.
  135.  
  136.    INPUTS
  137.        TagList   - optional pointer to tag array.  May be NULL.  For
  138.                    OS v1.3, there are restrictions on the tag array
  139.                    contents.  See NOTE below.
  140.  
  141.    TAGS
  142.             See SetMidiAttrsA
  143.  
  144.    RESULTS
  145.        A pointer to a MidiNode structure on success or NULL on failure.
  146.        When FALSE is returned, an error code will be returned if a TagItem
  147.         with an ti_Tag of MIDI_ErrorCode was provided. The CME_ error code
  148.         will be put in the ti_Data field.
  149.  
  150.    NOTE
  151.        Under 1.3 only a restricted tag array may be passed into this
  152.        funciton. Specifically, the only special tag values that are
  153.        supported are TAG_END (or TAG_DONE) and TAG_IGNORE.  All others
  154.        (e.g. TAG_SKIP, TAG_MORE) are treated as TAG_END.  The full range of
  155.        TAG list operations are permitted under 2.0.
  156.  
  157.        This function MUST be called by a Process (not a Task).  It makes a
  158.        few DOS calls.
  159.  
  160.        Don't call WaitMidi() with a send-only MidiNode.
  161.  
  162.    EXAMPLES
  163.        mi = CreateMidi (
  164.                MIDI_MsgQueue, 2048, MIDI_SysExSize, 10000L, TAG_END);
  165.  
  166.        Creates a MidiNode with space to receive 2048 MidiMsg's and 10000
  167.        bytes of Sys/Ex data.  Note the 'L' on the end of 10000.  This
  168.        forces correct alignment of the tag items on the stack for 16 bit
  169.        integer compilation.
  170.  
  171.    SEE ALSO
  172.        DeleteMidi(), SetMidiAttrs()
  173.        2.0 tag docs.
  174. camd.library/DeleteMidi                                 camd.library/DeleteMidi
  175.  
  176.    NAME
  177.        DeleteMidi -- Delete a MidiNode.
  178.  
  179.    SYNOPSIS
  180.        void DeleteMidi (struct MidiNode *mn)
  181.                                a0
  182.  
  183.    FUNCTION
  184.        Deletes the specified MidiNode.  A sys/ex queue allocated by
  185.        CreateMidi() is freed.  The following actions are automatically
  186.        performed by this function:
  187.  
  188.        A client-supplied sys/ex queue attached with SetSysExQueue() will
  189.        not be freed by this function.
  190.  
  191.    INPUTS
  192.        mn - MidiNode to delete. Can be NULL.
  193.  
  194.    RESULTS
  195.        None
  196.  
  197.    SEE ALSO
  198.        CreateMidi(), ClearSysExQueue()
  199. camd.library/EndClusterNotify                     camd.library/EndClusterNotify
  200.  
  201.    NAME
  202.        EndClusterNotify -- Stop notification of cluster changes
  203.  
  204.    SYNOPSIS
  205.        void EndClusterNotify (struct ClusterNotifyNode *cn)
  206.                                        a0
  207.  
  208.    FUNCTION
  209.        Terminates notification of CAMD internal state changes
  210.  
  211.    INPUTS
  212.        cn - a pointer to a ClusterNotifyNode
  213.  
  214.    RESULTS
  215.        None
  216.  
  217.    SEE ALSO
  218.        StartClusterNotify
  219. camd.library/FindCluster                               camd.library/FindCluster
  220.  
  221.    NAME
  222.        FindCluster -- Find a MidiCluster by name
  223.  
  224.    SYNOPSIS
  225.        struct MidiCluster *FindCluster (name)
  226.                                   a0
  227.  
  228.    FUNCTION
  229.        Find a MidiCluster by name. If a node of that name exists, the
  230.        function returns NULL. Midi links (CD_Linkages) must be locked when
  231.        called.
  232.  
  233.    INPUTS
  234.        name - name of MidiCluster to find.
  235.  
  236.    RESULTS
  237.        result - A MidiCluster or NULL.
  238.  
  239. camd.library/FindMidi                                     camd.library/FindMidi
  240.  
  241.    NAME
  242.        FindMidi -- Find a MidiNode by name
  243.  
  244.    SYNOPSIS
  245.        struct MidiNode *FindMidi (name)
  246.                                   a0
  247.  
  248.    FUNCTION
  249.        Find a MidiNode by name. If a node of that name exists, the function
  250.        returns NULL. Midi links (CD_Linkages) must be locked when called.
  251.  
  252.    INPUTS
  253.        name - name of MidiNode to find.
  254.  
  255.    RESULTS
  256.        result - A MidiNode or NULL.
  257.  
  258. camd.library/FlushMidi                                   camd.library/FlushMidi
  259.  
  260.    NAME
  261.        FlushMidi -- Dispose of all pending messages.
  262.  
  263.    SYNOPSIS
  264.        void FlushMidi (struct MidiNode *mi)
  265.                                a0
  266.  
  267.    FUNCTION
  268.        Disposes of all messages waiting to be received by GetMidi() and
  269.        GetSysEx().  Also clears pending errors.
  270.  
  271.    INPUTS
  272.        mi - MidiNode to flush.
  273.  
  274.    RESULTS
  275.        None
  276. camd.library/GetMidi                                       camd.library/GetMidi
  277.  
  278.    NAME
  279.        GetMidi -- Get next MidiMsg from buffer.
  280.  
  281.    SYNOPSIS
  282.        BOOL GetMidi (struct MidiNode *mn, MidiMsg *msg)
  283.                              a0                 a1
  284.  
  285.    FUNCTION
  286.        Gets the next MidiMsg from mn->MsgQueue.
  287.  
  288.        It is definitely not safe to call this if there's no MsgQueue.
  289.  
  290.    INPUTS
  291.        mn - pointer to MidiNode.
  292.        msg - pointer to buffer to place MidiMsg removed from
  293.          queue.
  294.  
  295.    RESULTS
  296.        TRUE if a MidiMsg was actually copied in msg.  FALSE
  297.        if the buffer was empty.
  298.  
  299.    SEE ALSO
  300.        WaitMidi()
  301. camd.library/GetMidiAttrsA                           camd.library/GetMidiAttrsA
  302.  
  303.    NAME
  304.        GetMidiAttrsA -- Get the attributes of a MidiNode
  305.  
  306.    SYNOPSIS
  307.        ULONG GetMidiAttrsA (struct MidiNode *mi, struct TagItem *attrs)
  308.                                        a0          a1
  309.    FUNCTION
  310.        Gets attributes of a MidiNode.
  311.  
  312.    INPUTS
  313.        mi - a pointer to the MidiNode
  314.  
  315.        attrs - Attributes to get, terminated with TAG_DONE.  The data
  316.            element of each pair contains the address of the storage
  317.            variable.
  318.  
  319.    RESULTS
  320.         Count of attributes understood.
  321.  
  322.    NOTE
  323.         Not implemented yet. Does nothing at this time.
  324.  
  325.    EXAMPLES
  326.  
  327.    SEE ALSO
  328.        SetMidiAttrs()
  329. camd.library/GetMidiErr                                 camd.library/GetMidiErr
  330.  
  331.    NAME
  332.        GetMidiErr -- Read accumulated MIDI error flags.
  333.  
  334.    SYNOPSIS
  335.        UBYTE GetMidiErr (struct MidiNode *mn)
  336.                                  a0
  337.  
  338.    FUNCTION
  339.        Returns the current MIDI error flags from the MidiNode.  The error
  340.        flags are cleared after reading.  Some error flags, such as
  341.        CMEF_BufferFull, prevent additional MIDI reception and must be
  342.        cleared in order to restart MIDI reception.
  343.  
  344.        Only bits enabled by SetMidiErrFilter() are returned as 1 bits.
  345.  
  346.    INPUTS
  347.        mn - MidiNode to check.
  348.  
  349.    RESULTS
  350.        CMEF_ error flags or 0 if no errors were present.  The upper 24 bits
  351.        are cleared for the caller's convenience.
  352.  
  353.    SEE ALSO
  354.        SetMidiErrFilter(), WaitMidi()
  355. camd.library/GetMidiLinkAttrsA                   camd.library/GetMidiLinkAttrsA
  356.  
  357.    NAME
  358.        GetMidiLinkAttrsA -- Get attributes of a MidiLink
  359.  
  360.    SYNOPSIS
  361.        ULONG GetMidiLinkAttrsA (struct MidiLink *ml, struct TagItem *attrs)
  362.                                        a0             a1
  363.  
  364.    FUNCTION
  365.        Gets an attribute of a MidiLink.
  366.  
  367.    INPUTS
  368.        mi - a pointer to the MidiLink
  369.  
  370.        attrs - Attributes to get, terminated with TAG_DONE.  The data
  371.            element of each pair contains the address of the storage
  372.            variable.
  373.  
  374.    RESULTS
  375.         Count of attributes understood.
  376.  
  377.    NOTE
  378.         Not implemented yet. Does nothing at this time.
  379.  
  380.    EXAMPLES
  381.  
  382.    SEE ALSO
  383.        SetMidiLinkAttrs()
  384. camd.library/GetSysEx                                     camd.library/GetSysEx
  385.  
  386.    NAME
  387.        GetSysEx -- Read bytes from Sys/Ex buffer.
  388.  
  389.    SYNOPSIS
  390.        ULONG GetSysEx (struct MidiNode *mn, UBYTE *Buf, ULONG Len)
  391.                               a0              a1          d0
  392.  
  393.    FUNCTION
  394.        Reads bytes from the Sys/Ex buffer for the current sys/ex message
  395.        into the supplied buffer.  This function will not read past the end
  396.        of the current sys/ex message.  The actual number of bytes read is
  397.        returned.  0 is returned when there are no more bytes to be read for
  398.        the current sys/ex message.  If the current message is not a sys/ex
  399.        message, this function will return 0.
  400.  
  401.    INPUTS
  402.        mn      - Pointer to MidiNode.
  403.        Buf - Output buffer pointer.
  404.        Len - Max number of bytes to read.
  405.  
  406.    RESULTS
  407.        Actual number of bytes read.
  408.  
  409.    SEE ALSO
  410.        GetMidi(), SkipSysEx(), QuerySysEx()
  411. camd.library/LockCAMD                                     camd.library/LockCAMD
  412.  
  413.    NAME
  414.        LockCAMD -- Prevent other tasks from changing internal structures
  415.  
  416.    SYNOPSIS
  417.        LockCAMD(locktype)
  418.                 d0
  419.        APTR LockCAMD( ULONG );
  420.  
  421.    FUNCTION
  422.        This routine will lock the internal sempahores in the CAMD library.
  423.        If they are already locked by another task, this routine will wait
  424.         until they are free.
  425.  
  426.    INPUTS
  427.        locktype -- which internal list will be locked.
  428.          CL_LINKS -- locks the internal list of MidiInterfaces, MidiLinks
  429.              and MidiClusters. Any functions that create or delete
  430.              these structures (including SetMidiLinkAttrs) will be locked.
  431.  
  432.    RESULT
  433.        If locktype is valid, returns a value that must be passed later
  434.         to UnlockCAMD.
  435.  
  436.    EXAMPLE
  437.  
  438.    NOTES
  439.  
  440.    BUGS
  441.  
  442.    SEE ALSO
  443.        UnlockCAMD(), CreateMidi(), DeleteMidi(),
  444.                AddLink(), RemoveMidiLink(), SetMidiLinkAttrs();
  445.  
  446. camd.library/MidiLinkConnected                   camd.library/MidiLinkConnected
  447.  
  448.    NAME
  449.        MidiLinkConnected -- Determine if MidiLink has a connection
  450.  
  451.    SYNOPSIS
  452.        BOOL MidiLinkConnected (struct MidiLink *ml)
  453.                                       a0
  454.  
  455.    FUNCTION
  456.        Returns TRUE if a MidiLink can currently send or receive to anyone.
  457.         For a MidiLink of type MLTYPE_Sender, then there must be at least
  458.         one MidiLink of type MLTYPE_Receiver linked to the same MidiCluster,
  459.         and vice versa.
  460.  
  461.    INPUTS
  462.        ml - MidiLink to check
  463.  
  464.    RESULTS
  465.        result - TRUE if there is a connection, FALSE otherwise
  466.  
  467. camd.library/MidiMsgLen                                 camd.library/MidiMsgLen
  468.  
  469.    NAME
  470.        MidiMsgLen -- Determine the length of a MIDI message
  471.  
  472.    SYNOPSIS
  473.        WORD MidiMsgLen (ULONG StatusByte)
  474.                           d0
  475.  
  476.    FUNCTION
  477.        Returns the length in bytes of the MIDI message described by the
  478.        supplied status byte.  The message length includes the status byte.
  479.  
  480.    INPUTS
  481.        StatusByte - UBYTE containing status byte.
  482.  
  483.    RESULTS
  484.        length - length of the message in bytes.  For valid messages this
  485.             will be at least 1.  0 is returned for invalid messages,
  486.             MS_SysEx and MS_EOX.
  487.  
  488.             The result is sign extended to 32 bits for assembly
  489.             programmers.
  490.  
  491.    SEE ALSO
  492.        MidiMsgType()
  493. camd.library/MidiMsgType                               camd.library/MidiMsgType
  494.  
  495.    NAME
  496.        MidiMsgType -- Determine the type of a MIDI message
  497.  
  498.    SYNOPSIS
  499.        WORD MidiMsgType (MidiMsg *Msg)
  500.                           a0
  501.  
  502.    FUNCTION
  503.        Returns a type bit number (CMB_) for supplied MidiMsg.
  504.  
  505.    INPUTS
  506.        Msg - Pointer to a MidiMsg.
  507.  
  508.    RESULTS
  509.        CMB_ bit number of message type.  -1 if message is undefined.  Also
  510.        -1 is returned for MS_EOX since it's not legal to be passed through
  511.        PutMidi().  The result is sign extended to 32 bits for assembly
  512.        programmers.
  513.  
  514.    SEE ALSO
  515.        MidiMsgLen()
  516. camd.library/NextCluster                               camd.library/NextCluster
  517.  
  518.    NAME
  519.        NextCluster -- Get next MidiCluster
  520.  
  521.    SYNOPSIS
  522.        struct MidiCluster *NextCluster (struct MidiCluster *last)
  523.                                                   a0
  524.  
  525.    FUNCTION
  526.        Returns the next MidiCluster on CAMD MidiCluster list. If last
  527.         is NULL, returns the first MidiCluster. Returns NULL if no more
  528.         MidiClusters. Midi links (CD_Linkages) must be locked when called.
  529.  
  530.    INPUTS
  531.        last - previous MidiCluster or NULL to get first MidiCluster
  532.  
  533.    RESULTS
  534.        next - next MidiCluster or NULL
  535.  
  536. camd.library/NextClusterLink                       camd.library/NextClusterLink
  537.  
  538.    NAME
  539.        NextClusterLink -- Get next MidiLink of one type in a MidiCluster
  540.  
  541.    SYNOPSIS
  542.        struct MidiLink *NextClusterLink (struct MidiCluster *mc,
  543.                                                   a0
  544.                         struct MidiLink *last, LONG type)
  545.                                 a1                d0
  546.  
  547.    FUNCTION
  548.        Returns the next MidiLink of a particular type a MidiCluster's list
  549.         of MidiLinks. If last is NULL, returns the first MidiLink. Returns
  550.         NULL if no more MidiLinks. Midi links (CD_Linkages) must be locked
  551.         when called.
  552.  
  553.    INPUTS
  554.        last - previous MidiLink or NULL to get first MidiLink
  555.  
  556.    RESULTS
  557.        next - next MidiLink or NULL
  558.  
  559. camd.library/NextMidi                                     camd.library/NextMidi
  560.  
  561.    NAME
  562.        NextMidi -- Get next MidiNode
  563.  
  564.    SYNOPSIS
  565.        struct MidiNode *NextMidi (struct MidiNode *last)
  566.                                   a0
  567.  
  568.    FUNCTION
  569.        Returns the next MidiNode on CAMD MidiNode list. If last is NULL,
  570.         returns the first MidiNode. Returns NULL if no more MidiNodes.
  571.         Midi links (CD_Linkages) must be locked when called.
  572.  
  573.    INPUTS
  574.        last - previous MidiNode or NULL to get first MidiNode
  575.  
  576.    RESULTS
  577.        next - next MidiNode or NULL
  578.  
  579. camd.library/NextMidiLink                             camd.library/NextMidiLink
  580.  
  581.    NAME
  582.        NextMidiLink -- Get next MidiLink of one type in a MidiNode
  583.  
  584.    SYNOPSIS
  585.        struct MidiLink *NextMidiLink (struct MidiNode *mi,
  586.                                                   a0
  587.                         struct MidiLink *last, LONG type)
  588.                                 a1                d0
  589.  
  590.    FUNCTION
  591.        Returns the next MidiLink of a particular type in a MidiNode's list
  592.         of MidiLinks. If last is NULL, returns the first MidiLink. Returns
  593.         NULL if no more MidiLinks. Midi links (CD_Linkages) must be locked
  594.         when called.
  595.  
  596.    INPUTS
  597.        last - previous MidiLink or NULL to get first MidiLink
  598.        type - MLTYPE_Sender or MLTYPE_Receiver
  599.  
  600.    RESULTS
  601.        next - next MidiLink or NULL
  602.  
  603. camd.library/OpenMidiDevice                         camd.library/OpenMidiDevice
  604.  
  605.    NAME
  606.        OpenMidiDevice -- Open a MIDI device driver.
  607.  
  608.    SYNOPSIS
  609.        struct MidiDeviceData *OpenMidiDevice (UBYTE *Name)
  610.                                                 a0
  611.  
  612.    FUNCTION
  613.        Opens a MIDI device driver.
  614.  
  615.        This function should only be called by Preferences program that
  616.        wishes to interrogate a particular MIDI device driver for such
  617.        information as number of Ports.
  618.  
  619.        Otherwise this is a private camd.library function.
  620.  
  621.    INPUTS
  622.        Name - name of MIDI device driver.
  623.  
  624.    RESULTS
  625.        Pointer to MidiDeviceData structure or NULL on failure.
  626.  
  627.    SEE ALSO
  628.        CloseMidiDevice()
  629. camd.library/ParseMidi                                   camd.library/ParseMidi
  630.  
  631.    NAME
  632.        ParseMidi -- Parse a stream of bytes as MIDI messages.
  633.  
  634.    SYNOPSIS
  635.        void ParseMidi (struct MidiLink *ml, UBYTE *Buffer,
  636.                              a0                 a1
  637.  
  638.                    ULONG Length)
  639.                          d0
  640.  
  641.    FUNCTION
  642.        Parses an unformated stream of bytes as MIDI data and transmits the
  643.        resulting messages to mi->SendPort.
  644.  
  645.        SetMidiLinkAttrs() must be called with MLINK_Parse set to TRUE prior
  646.        to calling ParseMidi() in order to attach the necessary parser data
  647.        to the MidiLink.
  648.  
  649.    INPUTS
  650.        mi         - a MidiLink to send on.
  651.        Buffer - Pointer to buffer containing MIDI data to send.
  652.        Length - Number of bytes in buffer to send.
  653.  
  654.    RESULTS
  655.        None
  656.  
  657.    SEE ALSO
  658.        SetMidiLinkAttrs()
  659. camd.library/PutMidi                                       camd.library/PutMidi
  660.  
  661.    NAME
  662.        PutMidi -- Send a MidiMsg to an output link
  663.  
  664.    SYNOPSIS
  665.        void PutMidi (struct MidiLink *link, ULONG Msg)
  666.                        a0                  d0
  667.  
  668.    FUNCTION
  669.        Sends the a MidiMsg to the output link specified.
  670.        The message is automatically timestamped.
  671.  
  672.    INPUTS
  673.        Msg - mm_Msg long word component of a MidiMsg.
  674.  
  675.    RESULTS
  676.        None
  677.  
  678.    NOTE
  679.        Although this function doesn't require a MidiNode pointer, the
  680.        caller must have allocated a MidiNode using CreateMidi() in
  681.        order for any messages to be distributed.
  682.  
  683.    SEE ALSO
  684.        PutMidi()
  685. camd.library/PutMidiMsg                                 camd.library/PutMidiMsg
  686.  
  687.    NAME
  688.        PutMidiMsg (MACRO) -- Send a MidiMsg.
  689.  
  690.    SYNOPSIS
  691.        void PutMidiMsg (struct MidiLink *ml, MidiMsg *msg)
  692.                             a0                 a1
  693.  
  694.    FUNCTION
  695.        Sends a MidiMsg. This is a macro that calls PutMidi().
  696.        The value in msg->mm_Port is ignored.
  697.        This macro exists in both C and Assembly.
  698.  
  699.    INPUTS
  700.        ml      - pointer to MidiLink.
  701.        msg - pointer to a MidiMsg to send.  Only the mm_Msg segment is
  702.          used.
  703.  
  704.    RESULTS
  705.        None
  706.  
  707.    SEE ALSO
  708.        GetMidi(), PutMidi()
  709. camd.library/PutSysEx                                     camd.library/PutSysEx
  710.  
  711.    NAME
  712.        PutSysEx -- Send a Sys/Ex Message to a link.
  713.  
  714.    SYNOPSIS
  715.        void PutSysEx (struct MidiLink *ml, UBYTE *Buffer)
  716.                               a0          a1
  717.  
  718.    FUNCTION
  719.        Sends the sys/ex message to the specified output link.
  720.  
  721.        Sys/Ex messages are sent to hardware units regardless of transmit
  722.         buffer size.  Distribution pauses until the entire sys/ex message
  723.         is placedin the transmit queue.
  724.  
  725.        Distribution to MidiNodes is a bit different.  If the sys/ex message
  726.        is greater than the MidiNode's sys/ex buffer, then the message will
  727.        not be sent to the MidiNode.  If the message is smaller than the
  728.         MidiNode's sys/ex buffer, but there's not enough room left in the
  729.         buffer to contain the sys/ex message, CMEF_SysExFull will be sent
  730.         to the MidiNode. Otherwise the sys/ex message will be sent.
  731.  
  732.    INPUTS
  733.        ml     - MidiLink to send Sys/Ex to
  734.        Buffer - Pointer to a Sys/Ex message beginning with MS_SysEx and
  735.             ending with MS_EOX.
  736.  
  737.    RESULTS
  738.        None
  739.  
  740.    NOTE
  741.        Although this function doesn't require a MidiNode pointer, the
  742.        caller must have allocated a MidiNode using CreateMidi() in
  743.        order for any messages to be distributed.
  744.  
  745.    SEE ALSO
  746.        PutSysEx()
  747. camd.library/QuerySysEx                                 camd.library/QuerySysEx
  748.  
  749.    NAME
  750.        QuerySysEx -- Get number of bytes remaining in current Sys/Ex
  751.                  message.
  752.  
  753.    SYNOPSIS
  754.        ULONG QuerySysEx (struct MidiNode *mn)
  755.                                 a0
  756.  
  757.    FUNCTION
  758.        Returns the number of bytes remaining in the current sys/ex message.
  759.  
  760.    INPUTS
  761.        mn - pointer to MidiNode
  762.  
  763.    RESULTS
  764.        Remaining bytes in sys/ex message.      0 is returned if the last
  765.        message read from GetMidi() wasn't a sys/ex message.
  766.  
  767.    SEE ALSO
  768.        GetSysEx(), GetMidi()
  769. camd.library/RemoveMidiLink                         camd.library/RemoveMidiLink
  770.  
  771.    NAME
  772.        RemoveMidiLink -- Removes a MidiLink from a MidiCluster.
  773.  
  774.    SYNOPSIS
  775.        void RemoveMidiLink (struct MidiLink *ml)
  776.                                   a0
  777.    FUNCTION
  778.        Removes a MidiLink structure from a MidiCluster.
  779.  
  780.    INPUTS
  781.         ml - MidiLink to remove. Can be NULL.
  782.  
  783.    SEE ALSO
  784.        AddMidiLinkA()
  785. camd.library/RethinkCAMD                               camd.library/RethinkCAMD
  786.  
  787.    NAME
  788.        RethinkCAMD -- Force CAMD library to reload MIDI preferences
  789.  
  790.    SYNOPSIS
  791.        LONG RethinkCAMD(void)
  792.  
  793.    FUNCTION
  794.        Forces CAMD library to reload MIDI preferences and reassign the
  795.         hardware unit MidiLinks.
  796.  
  797.    RESULTS
  798.        result - 0 if everything went OK, else returns a CME_ error code
  799.  
  800. camd.library/SetMidiAttrs                             camd.library/SetMidiAttrs
  801.  
  802.    NAME
  803.        SetMidiAttrs -- Set the attributes of a MidiNode
  804.  
  805.    SYNOPSIS
  806.        BOOL SetMidiAttrsA (struct MidiNode *mi, struct TagItem *tags)
  807.                                        a0          a1
  808.  
  809.        BOOL SetMidiAttrs (struct MidiNode *mi, ...)
  810.  
  811.    FUNCTION
  812.        Sets the attributes of a MidiNode, using a Tag List.
  813.  
  814.        The first form of the function expects a tag array pointer or NULL.
  815.        The second form permits the tag items to exist on the caller's
  816.        stack.  In both cases, the final tag item must be TAG_END.
  817.  
  818.    INPUTS
  819.        mi - a pointer to the MidiNode
  820.  
  821.        TagList   - optional pointer to tag array.  May be NULL.  For
  822.                    OS v1.3, there are restrictions on the tag array
  823.                    contents.  See NOTE below.
  824.  
  825.    TAGS
  826.          MIDI_Name         STRPTR - ti_Data points to the new name of
  827.                                the node (generally the Application name)
  828.  
  829.          MIDI_SignalTask   struct Task * - the task to be signaled whenever
  830.                    a MidiMsg or Participant change occurs. This is set
  831.                    by CreateMidi to the current task as a default
  832.  
  833.          MIDI_RecvHook     struct Hook * - this hook will be called when
  834.                    new MidiMsgs arrive, if the buffer was empty. If the buffer
  835.                    was not yet empty, then it is simply added onto the end.
  836.  
  837.          MIDI_PartHook     struct Hook * - this hook will be called whenever
  838.                    any of the clusters that this node is linked to either
  839.                    adds or removes a member.
  840.  
  841.          MIDI_RecvSignal   BYTE - the signal to send whenever an incoming
  842.                    MidiMsg arrives in the buffer, or -1 to send no signal
  843.  
  844.          MIDI_PartSignal   BYTE - the signal to send whenever a cluster
  845.                    to which this node is linked has a participant change,
  846.                    or -1 to send no signal
  847.  
  848.          MIDI_MsgQueue     ULONG - ti_Data specifies the size of the
  849.                    MsgQueue for this MidiNode. An additional pad MidiMsg
  850.                    is allocated for overflow protection. It can also be
  851.                    set to zero to indicate that no buffer should be allocated
  852.                    (A send-only MidiNode)
  853.  
  854.          MIDI_SysExSize   ULONG - ti_Data specifies the size of the SysExQueue
  855.                    in bytes. Like the MsgQueue, an additional byte is
  856.                    allocated to allow for overflow protection.
  857.  
  858.          MIDI_TimeStamp   ULONG * - if non-NULL, ti_Data is a pointer to
  859.                    a longword which is to be used as the source for time
  860.                    stamps of incoming MidiMsgs for this MidiNode. It is
  861.                    assumed that the longword pointed to will be updated by
  862.                    some other mechanism -- for example, the longword could
  863.                    point to one of the fields in a PlayerInfo structure.
  864.  
  865.          MIDI_ErrFilter   UWORD - specified the ErrFilter for this MidiNode
  866.  
  867.          MIDI_ClientType  UWORD - specified the Client Type for this MidiNode
  868.                    See camd.h for more detail.
  869.  
  870.          MIDI_Image       struct Image * - pointer to an Intuition Image
  871.                    structure representing a glyph or icon that is symbolic
  872.                    if this application. Will be used for a future "patch
  873.                    bay" application. It is suggested that images be
  874.                    approximately 32 wide x 32 high, for consistency.
  875.  
  876.    RESULTS
  877.        TRUE if all changes were made successfully or FALSE on failure.
  878.        When FALSE is returned, an error code will be returned if a TagItem
  879.         with an ti_Tag of MIDI_ErrorCode was provided. The CME_ error code
  880.         will be put in the ti_Data field.
  881.  
  882.    NOTE
  883.        Under 1.3 only a restricted tag array may be passed into this
  884.        funciton. Specifically, the only special tag values that are
  885.        supported are TAG_END (or TAG_DONE) and TAG_IGNORE.  All others
  886.        (e.g. TAG_SKIP, TAG_MORE) are treated as TAG_END.  The full range of
  887.        TAG list operations are permitted under 2.0.
  888.  
  889.        This function MUST be called by a Process (not a Task).  It makes a
  890.        few DOS calls.
  891.  
  892.        Don't call WaitMidi() with a MidiNode that has no ReceiveSignal.
  893.  
  894.    EXAMPLES
  895.        mi = SetMidiAttrs (mi,
  896.                MIDI_MsgQueue, 2048, MIDI_SysExSize, 10000L, TAG_END);
  897.  
  898.        Modifies a MidiNode to have space to receive 2048 MidiMsg's and 10000
  899.        bytes of Sys/Ex data.  Note the 'L' on the end of 10000.  This
  900.        forces correct alignment of the tag items on the stack for 16 bit
  901.        integer compilation.
  902.  
  903.    SEE ALSO
  904.        CreateMidi(), DeleteMidi()
  905.        2.0 tag docs.
  906. camd.library/SetMidiLinkAttrs                     camd.library/SetMidiLinkAttrs
  907.  
  908.    NAME
  909.        SetMidiLinkAttrs -- Set the attributes of a MidiNode
  910.  
  911.    SYNOPSIS
  912.        BOOL SetMidiLinkAttrsA (struct MidiLink *ml, struct TagItem *tags)
  913.                                        a0          a1
  914.  
  915.        BOOL SetMidiLinkAttrs (struct MidiLink *mi, Tag type1, ...)
  916.  
  917.    FUNCTION
  918.        Sets the attributes of a MidiLink, using a Tag List.
  919.  
  920.        The first form of the function expects a tag array pointer or NULL.
  921.        The second form permits the tag items to exist on the caller's
  922.        stack.  In both cases, the final tag item must be TAG_END.
  923.  
  924.    INPUTS
  925.        ml - a pointer to the MidiLink
  926.  
  927.        TagList   - optional pointer to tag array.  May be NULL.  For
  928.                    OS v1.3, there are restrictions on the tag array
  929.                    contents.  See NOTE below.
  930.  
  931.    TAGS
  932.        MLINK_Name         STRPTR - ti_Data points to the new name of
  933.                              the node
  934.  
  935.        MLINK_Location     STRPTR - ti_Data points to name of MidiCluster
  936.                               to link with
  937.  
  938.         MLINK_ChannelMask  UWORD - ti_Data contains mask of which MIDI
  939.                               channels to listen for (defaults to ~0)
  940.  
  941.         MLINK_EventMask    UWORD - ti_Data contains mask of which types
  942.                               of MIDI events to listen for (defaults to ~0)
  943.  
  944.         MLINK_UserData     CPTR - ti_Data points to user definable data
  945.  
  946.         MLINK_Comment      STRPTR - ti_Data points to a comment string. The
  947.                               highest priority MidiLink in a MidiCluster
  948.                               has its comment field copied to the
  949.                               MidiCluster's comment field
  950.  
  951.         MLINK_PortID       UBYTE - ti_Data contains value to copy into any
  952.                               MidiMsg's arriving at MidiNode through this
  953.                               MidiLink (defaults to 0)
  954.  
  955.         MLINK_Private      BOOL - if ti_Data contains TRUE, then this link
  956.                               requests to not be shown by "patch bay"
  957.                               editors, etc.
  958.  
  959.         MLINK_Priority     BYTE - ti_Data contains priotity of the MidiLink
  960.  
  961.         MLINK_SysExFilter  ULONG - ti_Data contains three 1-byte manufacturor
  962.                               numbers to filter SysEx messages with
  963.  
  964.         MLINK_SysExFilterX ULONG - ti_Data contains one 3-byte manufacturor
  965.                               number to filter SysEx messages with
  966.  
  967.         MLINK_Parse        BOOL - if ti_Data contains true, allocate a parser
  968.                               for the MidiLink so raw MIDI streams can be
  969.                               sent though the link
  970.  
  971.         MLINK_ErrorCode    ULONG * - ti_Data points to an error code buffer
  972.  
  973.    RESULTS
  974.        TRUE if all changes were made successfully or FALSE on failure.
  975.        When FALSE is returned, an error code will be returned if a TagItem
  976.         with an ti_Tag of MLINK_ErrorCode was provided. The CME_ error code
  977.         will be put in the ti_Data field.
  978.  
  979.    NOTE
  980.        Under 1.3 only a restricted tag array may be passed into this
  981.        funciton. Specifically, the only special tag values that are
  982.        supported are TAG_END (or TAG_DONE) and TAG_IGNORE.  All others
  983.        (e.g. TAG_SKIP, TAG_MORE) are treated as TAG_END.  The full range of
  984.        TAG list operations are permitted under 2.0.
  985.  
  986.    EXAMPLES
  987.        mi = SetMidiLinkAttrs (ml,
  988.                MLINK_Location, "out.0", MLINK_Priority, -5L, TAG_END);
  989.  
  990.        Modifies a MidiLink so it will be connected to the MidiCluster named
  991.         "out.0" and makes the MidiLink's priority -5. Note the 'L' on the end
  992.         of -5. This forces correct alignment of the tag items on the stack
  993.         for 16 bit integer compilation.
  994.  
  995.    SEE ALSO
  996.        AddMidiLink(), RemoveMidiLink()
  997.        2.0 tag docs.
  998. camd.library/SkipSysEx                                   camd.library/SkipSysEx
  999.  
  1000.    NAME
  1001.        SkipSysEx -- Skip the next sys/ex message in the Sys/Ex buffer.
  1002.  
  1003.    SYNOPSIS
  1004.        void SkipSysEx (struct MidiNode *mn)
  1005.                               a0
  1006.  
  1007.    FUNCTION
  1008.        Skips the remaining bytes of the current sys/ex message.  Nothing
  1009.        happens if the last message read from GetMidi() wasn't a sys/ex
  1010.        message.
  1011.  
  1012.    INPUTS
  1013.        mn - Pointer to MidiNode.
  1014.  
  1015.    RESULTS
  1016.        None.
  1017.  
  1018.    SEE ALSO
  1019.        GetSysEx()
  1020. camd.library/StartClusterNotify                 camd.library/StartClusterNotify
  1021.  
  1022.    NAME
  1023.        StartClusterNotify -- Notify task of cluster changes
  1024.  
  1025.    SYNOPSIS
  1026.        void StartClusterNotify (struct ClusterNotifyNode *cn)
  1027.                                        a0
  1028.  
  1029.    FUNCTION
  1030.        Allow an external task to receive notification via a signal that
  1031.        CAMD's internal state has changed. This function is mostly useful
  1032.        to "patch bay" editors, etc.
  1033.  
  1034.    INPUTS
  1035.        cn - a pointer to a ClusterNotifyNode
  1036.  
  1037.    RESULTS
  1038.        None
  1039.  
  1040.    EXAMPLES
  1041.  
  1042.         struct ClusterNotifyNode cnn;
  1043.  
  1044.         cnn.cnn_Task = FindTask(NULL);
  1045.         cnn.cnn_SigBit = AllocSignal(-1);
  1046.         StartCluserNotify(&cnn);
  1047.  
  1048.         /* later in code */
  1049.  
  1050.         Wait(1 << cnn.cnn_SigBit);
  1051.  
  1052.         /* someone changed the state of a cluster */
  1053.  
  1054.    SEE ALSO
  1055.        EndClusterNotify
  1056. camd.library/UnlockCAMD                                 camd.library/UnlockCAMD
  1057.  
  1058.    NAME
  1059.        UnlockCAMD -- Unlock internal lists
  1060.  
  1061.    SYNOPSIS
  1062.        UnlockCAMD(lock)
  1063.                    a0
  1064.        void UnlockCAMD( APTR );
  1065.  
  1066.    FUNCTION
  1067.        Undoes the effects of LockCAMD().
  1068.  
  1069.    INPUTS
  1070.        lock -- value returned by LockCAMD(). Can be NULL.
  1071.  
  1072.    EXAMPLE
  1073.  
  1074.    SEE ALSO
  1075.        LockCAMD()
  1076.  
  1077. camd.library/WaitMidi                                     camd.library/WaitMidi
  1078.  
  1079.    NAME
  1080.        WaitMidi -- Wait for next MidiMsg and get it.
  1081.  
  1082.    SYNOPSIS
  1083.        BOOL WaitMidi (struct MidiNode *mn, MidiMsg *msg)
  1084.                               a0                 a1
  1085.  
  1086.    FUNCTION
  1087.        Waits for the next MidiMsg to arrive at the MidiNode.  On reception,
  1088.        the MidiMsg is removed and copied to the supplied buffer.
  1089.  
  1090.        WaitMidi() first checks for errors detected at the MidiNode.  If
  1091.        none are detected, GetMidi() is called.  If the buffer was empty,
  1092.        Wait() is called until the MidiNode is signalled.  Once the signal
  1093.        arrives, this process is repeated.
  1094.  
  1095.    INPUTS
  1096.        mn  - pointer to MidiNode.
  1097.        msg - pointer to buffer to place MidiMsg removed from queue.
  1098.  
  1099.    RESULTS
  1100.        TRUE if a MidiMsg was received.  FALSE if an error was detected.
  1101.  
  1102.    SEE ALSO
  1103.        GetMidi()
  1104.